<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>


  
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

  


  
  <title>wxstedit.html</title>
  <meta content="John Labenski" name="author" />


  
  <meta content="readme.html for wxStEdit library" name="description" />
</head>


<body style="background-color: rgb(255, 255, 255);">


<h1>README for wxStEditor</h1>


<span style="font-weight: bold;">Copyright : 2005, John
Labenski, Otto
Wyss.</span><br />


<span style="font-weight: bold;">License : wxWindows
license.</span><br />


<br />


<span style="font-style: italic;">This library/program is
free
software; you can
redistribute it and/or modify it under the terms of the wxWindows
License; either version 3 of the License, or (at your option) any later
version.</span><br style="font-style: italic;" />


<br style="font-style: italic;" />


<span style="font-style: italic;">This library is
distributed in the
hope that it will
be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
wxWindows License for more details.</span><br />


<br />


If you use this program/library and find any bugs or
have added any features that you feel may be generally useful, please
feel free to contact the author by e-mail at
jrl1[at]sourceforge[dot]net.<br />


<br />


<h2>Summary :</h2>


wxStEdit is a library and sample program for the
wxWidgets's wxStyledTextCtrl wrapper around the Scintilla text editor
widget. It provides a number of convenience functions and added
capabilities, including the necessary preferences, styles, language
management, menu creation and updating, a splitter, notebook, and frame
component. Additionally it provides a find/replace, editor settings,
and property dialogs. It is designed to be easily integrated into a
larger program and while it tries to manage as much as possible, it's
fairly extensible as well. Individual features and "helper"
functionality can be turned off or overridden if desired.
<br />


<br />


The bottom line; this editor system builds upon the
wxStyledTextCtrl by adding all the necessary code to ease the burden of
providing a full featured editor or sets of identically styled editors
in a notebook or frame.
<br />


<br />


What does the ST in wxSTEditor stand for? Either styled text or
Scintilla text, your choice.<br />


<br />


It has been tested in MS Windows OS &gt;= 95 and *nix using GTK 1.2
or
2.0. <br />


The recommended version of wxWidgets is &gt;= 2.6.
<br />


The core for the editor was originally based on Otto Wyss's wxGuide
editor.
<br />


<br />


<h2>References :</h2>


http://wxcode.sourceforge.net
<br />


http://www.wxwidgets.org
<br />


http://www.scintilla.org
<br />


http://bakefile.sourceforge.net
<br />


<br />


<h2>Provides : (at a glance)</h2>


<h3>The main GUI classes :</h3>


<ul type="disc">


  <li align="left">wxSTEditor : a subclassed
wxStyledTextControl with additional functionality.</li>


  <li align="left">wxSTEditorSplitter : a subclassed
wxSplitterWindow
to split a wxSTEditor either horizontally or vertically.</li>


  
  <ul>


    <li align="left">Simplified splitter class that
automatically handles splitting and unsplitting</li>


  
  </ul>


  <li align="left">wxSTEditorNotebook : a subclassed
wxNotebook to
manage multiple wxSTEditorSplitters.</li>


  <li align="left">wxSTEditorFrame : a subclassed
wxFrame </li>


  
  <ul>


    <li align="left">Can create it's own
wxMenuBar, wxToolBar, wxStatusBar or not</li>


  
  </ul>


  
  <ul>


    <li align="left">Create wxSTEditorNotebook or
a single wxSTEditorSplitter as a child or neither</li>


    <li align="left">Can have typical IDE layout, vertical
splitter with listbox on left for files opened, notebook on right for
editing</li>


  
  </ul>


</ul>


<h3>Helper classes :</h3>


<ul type="disc">


  <li align="left">wxSTEditorEvent : alerts on status
change to keep
GUI updated</li>


  <li align="left">wxSTEditorRefData : easily allows
splitting editors
(used internally)</li>


</ul>


<ul type="disc">


  <li align="left">wxSTEditorPrefs : stores
string/int/bool preferences
for the editors</li>


  <li align="left">wxSTEditorStyles : stores colour/font
styles for the
editor</li>


  <li align="left">wxSTEditorLangs : stores lexer
information,
keywords, brackets</li>


</ul>


<ul type="disc">


  <li align="left">wxSTEditorOptions : options to control
behavior of
editor/splitter/frame and store data to be shared among editors</li>


  <li align="left">wxSTEditorMenuManager : create popup
menu/menubar/toolbar, enable/check items</li>


</ul>


<ul type="disc">


  <li align="left">wxSTEditorFindReplacePanel : an
embeddable
find/replace panel</li>


  <li align="left">wxSTEditorFindReplaceDialog : full
featured
find/replace dialog</li>


  <li align="left">wxSTEditorFindReplaceData : complete
find replace
data</li>


</ul>


<ul type="disc">


  <li align="left">wxSTEditorPrintout : Managed
wxPrintout, provides
printing </li>


  <li align="left">wxSTEditorPrintOptionsDialog : Display
Scintilla's
print options</li>


</ul>


<ul type="disc">


  <li align="left">wxSTEditorExporter : Export file to
RTF, HTML, PDF, TEX, XML</li>


</ul>


<ul type="disc">


  <li align="left">wxSTFrameFileDropTarget : a wxFileDrop
target for
the wxSTEditorFrame</li>


</ul>


<ul type="disc">


  <li align="left">wxSTEditorPropertiesDialog : file or
editor
properties dialog</li>


  <li align="left">wxSTEditorInsertTextDialog : insert
text dialog
(prepend, append, insert)</li>


</ul>


<ul type="disc">


  <li align="left">wxSTEditorPrefPageData : data for the
prefs/styles/langs setup</li>


  <li align="left">wxSTEditorPrefDialog : complete
preference, style,
langs dialog</li>


  <li align="left">wxSTEditorPrefDialogPagePrefs : a
generic page for
any assortment of wxSTEditorPrefs</li>


  <li align="left">wxSTEditorPrefDialogPageStyles : colour
styles page</li>


  <li align="left">wxSTEditorPrefDialogPageLangs :
languages page</li>


</ul>


<ul>


  <li>wxSTEditorShell : A console type interactive shell for user
entry, eg. a DOS prompt.</li>


</ul>


<h3>Others :</h3>


<ul type="disc">


  <li align="left">Creation and display of right click
menu for editor,
splitter, notebook (or not).</li>


  <li align="left">Printing dialogs and print data
management.</li>


  <li align="left">wxConfig saving and loading of prefs,
styles, and
langs in wxConfig::Get(false) is not NULL</li>


  <li align="left">Additional event notification events
and more...</li>


</ul>


<br />


Each component of the library can be used independently of the higher
level controls. In other words you can use the wxSTEditor class
independently of the others. The wxSTEditorSplitter only depends on the
wxSTEditor, the wxSTEditorNotebook depends on the splitter and editor,
and finally the wxSTEditorFrame on any one or all of the above.
<br />


You can subclass each or any of the controls and use them in
conjunction with the others. The order of what control is parent to
what is not important so long as the virtual functions like GetEditor()
work appropriately.
<br />


<br />


<h2>Example uses : (see also notes and code in the wxstedit
sample
program) </h2>


You're making an IDE type program, use the notebook to manage your
editor pages keeping the styles and preferences between all of them in
sync. Your output window can also be assigned the same styles to make
sure that it's colours are the same as the editors, but not the
preferences since the user shouldn't be allowed to change anything. All
editors should probably share the same languages.
<br />


Maybe you simply need a syntax highlighting widget for the user to
occasionally edit/view some text in, just use the wxSTEditor widget
itself.<br />


The user needs to edit a file in a frame, just create a
wxSTEditorFrame, create your options for it, and set the text or load a
file. Thats it! <br />


<br />


You can build it as a library and link to it or just add the files to
your existing project. You typically need only include
"wx/stedit/stedit.h". <br />


<br />


<h2>Compilation :</h2>


Compiles for wxWidgets version 2.6 and up, recommended version
&gt;=
2.6
<br />


Tested in Linux using gcc and wxGTK and wxMSW using MSVS 6&amp;7. <br />


<br />


<h3>Linux using GCC and gmake :</h3>


Use the Makefile in the src or samples/stedit directory which depends
on the wxWidget's 'wx-config' script being in the path. The Makefile in
the /src directory will create a library in the wxWidgets/lib directory
using the wxWidgets naming conventions. To create the library
elsewhere, change the variable $(WXLIBDIR) in the Makefile. <br />


<br />


The Makefile in the sample/stedit dir will automatically try to build
the library first and so you can simply run make in the samples/stedit
dir to build both. <br />


<br />


There is no "make install" for the sample, just copy or create a link
to it someplace in your path. You can use &ldquo;make
clean&rdquo; or &ldquo;make
cleanall&rdquo; in the sample directory to rebuild the sources. The
sample
will create a ~/.wxStEdit ini file.
<br />


<br />


<h3>MSW using MSVS :</h3>


Use the correct wxstedit_wx2X.dsp for the standalone editor sample and
steditlib_wx2X.dsp for a library to link to. The wxstedit_wx2X.dsw in
the samples/stedit directory can be used to build both the sample and
the library. You must have the WXWIN environment variable set to the
location of your copy of the wxWidgets source to use the project files.
In MS Win 9x you must edit your config.sys file and reboot. In 2k/XP
you can right click on &ldquo;My
Computer-&gt;Properties-&gt;Advanced-&gt;Environment
Variables&rdquo; and add
a user variable, you must restart MSVS for the change to take effect.
The output library is placed in the src/vc_mswX dir and the sample
program into the samples/stedit/vc_mswX dir.
<br />


<br />


<h3>Bakefile :</h3>


I am unable to test all of these configurations, the Microsoft 2003
free compiler has been tested however. Use these make and project files
in the same way that you would use them in the wxWidget's samples
directory.
<br />


<br />


Normally, you do not have to regenerate these... In the build directory
is a bakefile called &ldquo;stedit
.bkl&rdquo;. To
regenerate the make and project files run &ldquo;bakefile_gen"
stedit.bkl&rdquo;,
to regenerate a single type, like the Visual Studio project files for
example, use &ldquo;bakefile_gen -f msvs stedit.bkl&rdquo;.
<br />


The base files for bakefile are, stedit.bkl (the main bakefile),
Bakefile.bkgen (edit to point to stedit.bkl), and for gcc in linux
aclocal.m4, acregen.sh, config.guess, config.sub, configure.as.
<br />


<br />


<h2>Documentation :</h2>


The "full documentation" is included in the headers with a description
of the public functions. There is also a doxygen.cfg file in the "docs"
directory that you can use to create cross referenced html docs, please
review and adjust the file to your liking.
<br />


<br />


<h4>wxstedit.cpp : samples/stedit/wxstedit.cpp (wxstedit.exe for
MSW,
wxstedit for *nix)</h4>


Sample program that uses the wxSTEditorFrame to create a
standalone
editor executable. Its shows how little work is required to have a full
featured text editor. The wxstedit program uses a wxFileConfig meaning
that NO registry entries in MSW are created. Therefore no (un)installer
needed. It only creates a "Documents and Settings/user/wxStEdit.ini"
in MSW's NT OSs and ~/.wxStEdit *nix that you can delete if desired.
<br />


<br />


<h4>#defines and enums : include/wx/stedit/stedefs.h</h4>


<h3><u><i><b>NOTE:</b></i></u><i>
You must copy include/wx/stedit/setup0.h to setup.h</i></h3>


The include/wx/stedit/setup.h file is used to not compile in some of
the data for the different Scintialla lexers. Since there are quite a
few of them and each has their own keywords the amount of data is
fairly sizeable, see stelangs.cpp. By default all of them are turned
on.
<h4>wxSTEditor : include/wx/stedit/stedit.h</h4>


Subclassed from the wxStyledTextControl it provides some simplified
methods and many additional features. The internal data it uses is the
ref counted wxSTEditorData so that you can ref an editor (splitting for
example) and the rest of the data goes with it.
<br />


<ul type="disc">


  <li align="left">The editor can be used independently of
the other gui classes</li>


  <li align="left">Has wxTextCtrl compatibility functions
so it can be used as a drop-in replacement in some cases</li>


  <li align="left">Adds to the wxStyledTextCtrl a number
of functions including, but not limited to</li>


  
  <ul>


    <li align="left">PasteRectangular() - rectangular
pasting</li>


    <li align="left">AppendTextGotoEnd() - useful for log
type windows</li>


    <li align="left">GetWordCount(), GetEOLCount(), ...</li>


    <li align="left">Code folding simplification functions</li>


    <li align="left">ConvertTabsToSpaces() or reverse,
RemoveTrailingWhitespace()</li>


    <li align="left">Columize() - align text to be in
columns</li>


    <li align="left">Dialogs to set eol mode, columize,
zoom, goto line, properties</li>


    <li align="left">Load/Save that is unicode
aware</li>


    <li align="left">Export to a variety of formats</li>


    <li align="left">IsAlteredOnDisk() - check if file has
been modified</li>


    <li align="left">Indicator convenience functions</li>


    <li align="left">Printing and dialogs associated with
it</li>


    <li align="left">Updates all menu/toolbar items
assocated with it when it has focus</li>


    <li align="left">Highlight matching braces</li>


  
  </ul>


  <li align="left">Alerts parent of changes to
Cut/Copy/Paste/Save...
ability (for menus)</li>


  <li align="left">Event at the end of the constructor to
allow parent
classes to add/change features and styles to the editor without having
to subclass it.</li>


  <li align="left">Focus event so parent can know who's
focused and
update GUI items.</li>


  <li align="left">Set Toolbar and MenuBar for the editor
to manage and
update as necessary.</li>


  <li align="left">Find/Replace dialog management that
automatically
finds a splitter or notebook parent so that it works in both splitter
panes or on all the notebook pages.</li>


  <li align="left">Customizeable popup right click dialog,
or set your
own</li>


  <li align="left">Function to handle menu events,
returning if
anything was done.</li>


  <li align="left">Load/Save config to a wxConfigBase class</li>


  <li align="left">Abililty to have
preferences/styles/languages
managed by wxSTEditorPrefs/Styles/Langs (or some or none)</li>


</ul>


<br />


<h4>wxSTEditorSplitter : include/wx/stedit/stesplit.h</h4>


wxSplitter window to split editor document horizontally or vertically.
Can have it's own popup menu to aid in (un)splitting. Additionaly, it
gets rid of gtk errors when wxSTC is in a notebook, so it's a good idea
to always use this even if you don't want to allow splitting.
<br />


<br />


<h4>wxSTEditorNotebook : include/wx/stedit/stenoteb.h</h4>


A notebook that can manage the tab names, adds a right click menu to
add and remove pages. Also handles loading/saving multiple files and
searching though all files if the find replace dialog has this as a
parent. It's intended to have wxSTEditorSplitter pages, but
wxDynamicCast is used to verify each page before any action is taken
and if you have used some other type of window it will be left alone.
<br />


<br />


<h4>wxSTEditorFrame : include/wx/stedit/steframe.h</h4>


A wxFrame that can have a toolbar or not and either a single page
editor or a notebook for them. As with the notebook, it only adjusts
the children that it has created or that your subclassed frame returns
in the virtual functions to get the notebook, splitter, or editor. <br />


<br />


<h4>wxSTEditorFindReplaceData : include/wx/stedit/stefindr.h</h4>


<h4>wxSTEditorFindReplacePanel :</h4>


<h4>wxSTEditorFindReplaceDialog :</h4>


An enhanced find/replace dialog that uses all the find/replace
functionality of Scintilla. It stores multiple find/replace strings and
shows them in wxComboBoxes. It operates in the same way as the
wxFindReplaceDialog by sending events back to the parent. Use
wxSTEditor::ShowFindReplaceDialog and it will create one for you. If
the editor's parent is a splitter then the splitter will be the parent
of the dialog, if grandparent is the notebook then that will be the
parent. That way you can split/unsplit without loosing the dialog and
search through all the notebook pages. <br />


<br />


<h4>wxSTEditorOptions : include/wx/stedit/steopts.h</h4>


A simple class that stores different options for the editor, splitter,
notebook, frame, config (wxConfig), and menu items. These are options
to enable/disable features provided by this library, as opposed to the
wxSTEditorPrefs that only store prefs for the wxStyledTextCtrl. It also
stores popup menus for the editor, splitter, notebook and a menubar and
toolbar that you'll want to be updated. <br />


<br />


The options class is passed from parent to child so that once you set
it up the way you want any children will use the same options. You can
(of course) turn off all the options and then you're back to the
wxStyledTextCtrl's behavior.
<br />


<br />


<h4>wxSTEditorMenuManager : include/wx/stedit/stemenum.h</h4>


This is a class to create a full set of menus and add items to a
toolbar. You can control what menus are created by adjusting ored
together enum values. The functions can either create new menus for you
or just add items to the menu you send in.
<br />


<br />


The menu manager class also has static functions to update menu and
toolbar items that won't fail if the item doesn't exist.
<br />


<br />


<h4>wxSTEditorPrintout : include/wx/stedit/steprint.h</h4>


Print management/preview window. You can use your own wxPrintData
and/or wxPageSetupData or this will create it's own copy and delete it
when done.
<br />


<br />


<h4>wxSTEditorPrintOptionsDialog : include/wx/stedit/steprint.h</h4>


A print options dialog to adjust how Scintilla will print the pages.
Set the font zoom, wrap lines, and colour mode. <br />


<br />


<h4>wxSTEditorPrefDialog : include/wx/stedit/stedlgs.h</h4>


<h4>wxSTEditorPrefDialogPageBase...</h4>


Shows all the preferences that the wxSTC can have in a compact dialog.
Also lets you setup the styles (colouring for the editor) and view how
the lexer handles different languages.
<br />


<br />


<h4>wxSTEditorPropertiesDialog : include/wx/stedit/stedlgs.h</h4>


Gives for the properties for the editor page, word count, eol, etc.
<br />


<br />


<h4>wxSTEditorPrefs : include/wx/stedit/steprefs.h</h4>


A ref counted preference class for the wxSTEditor that controls ALL of
Scintilla's (wxSTEditor's) bool/int settings. This can get's attached
to one or many editors by calling wxSTEditor::RegisterPrefs(myPrefs).
It updates all the editors to have the same preferences automatically.
This stores all the bool/int wxSTC preferences like tab width,
wraplines, etc... Has functions to update menu items and load/save to a
wxConfigBase.
<br />


<br />


<h4>wxSTEditorStyles : include/wx/stedit/steprefs.h</h4>


A ref counted styles class to stores all the styles that the wxSTC uses
for colourizing a document. Comes with predefined values for styles
0-37 which you can (of course) change. Also stores some GUI styles like
cursor colour and what not as well as the indicator colours and can
load/save to a wxConfigBase.
<br />


<br />


A note on Scintilla's styles: Scintilla uses styles numbered 0-127,
with 33-37 used for gui colouring, see STE_StyleType. Different lexers
(languages) use different styles with different style numbers, they're
unfortunately almost random, but they do start from 0 and are (mostly)
contiguous. To simplify this a fixed set of styles are created numbered
0-32 that reasonably cover most of the styles used by the lexers. For
example, any language that has a comment style will use
STE_STYLE_COMMENT for that. Therefore you need only setup the styles
0-32 and any language should be appropriately styled. This way when a
user wants to do something as simple as change the colors to white on
black they only have to change it once and it works for any language.
<br />


<br />


<h4>wxSTEditorLangs : include/wx/stedit/steprefs.h</h4>


A ref counted language class for the wxSTC lexer to use. It uses the
wxSTEditorStyles to set the colours and stores it's own words for each
language. You probably only need one of these since the only thing that
you can currently change is what file extensions to associate with what
files. It contains information about every one of Scintilla's lexers,
some may be more complete than others however and I welcome any help
understanding the meaning of the styles for the more esoteric
languages.
<br />


<br />


<h2>Notes :</h2>


<h4>IMPORTANT!</h4>


Some systems will send focus events when shutting the app down. Since
the wxSTEditor sends it's own focus event to the parents to help you
update toolbars and whatnot, the window gets destroyed behind your back
and causes a segfault. The benefits of tracking the focus (instead of
using UpdateUI events) outweighs the extra care required. The solution
is simple however! Call the topmost window's
wxSTEditor/Splitter/Notebook/Frame::SendSTEEvents(false) in your
wxApp::OnExit or in your wxFrame's EVT_CLOSE handler to block all
wxSTEditor event processing for the window and all it's children. <br />


<br />


All wxSTEditorOptions are passed down to the children of each window.
For example, when you create a wxSTEditorFrame and call
frame-&gt;CreateOptions all the children will be created and then
CreateOptions with the parent's options called on them.
<br />


<br />


Events are passed to each child, eg. frame gets an event and calls bool
HandleEvent for the notebook which calls HandleEvent for the splitter
which calls HandleEvent for the current editor. Each HandleEvent
function returns true if it knows about the event ID and has dealt with
it. All the known event IDs are in stedefs.h
<br />


<br />


There are global versions of the preferences, styles, and languages
that are always created. You should use these for at least one "set" of
editors and create new ones for other editors if you want to allow
different prefs/styles for different editors. (you probably don't need
to create multiple languages)<br />


<br />


This file was edited using the Nvu composer and converted to text using
"html2text -nobs -ascii -o readme.txt readme.htm".<br />


<br />


</body>
</html>
